qacli view

This subcommand allows you to output the diagnostics from a previous analysis.

Usage

view [-P <directory>] [-K <config name>] [-C <solution-name>] [--cma-project <project-name>] [-R] [-t <ANNSRC|DIAGLST|SUMMARY|SARIF>] -m <HTML|STDERR|STDOUT|XML|JSON> [--output-name <filename prefix>] [-o <directory>] [-c] [-a] [-1] [-b] [-Z] [-e] [-F <filelist>] [-X <max-count-filter>] [-S <0|1|2|3|4|5|6|7|8|9>] [-v<0|1|2|3|4|5|6|7|8|9>] [-N <msg-filter>] [-O <msg-filter>] [-D <NONE|SINGLE|DUPLICATE>] [-M] [-T <ALL|BASELINE|COMMENT|DASHBOARD|INTERACTIVE|MACRO|PRAGMA|VALIDATE>] ...  [-s] [-n] [-r] [-f <format-string>] [-u <rule-format-string>] [-H <header-format-string>] [-x <xml-format-string>] [-d <xml-format-string>] [--xml-indent <indent>] [-i <indent>] [--] [-h] <source-file>

Extended Description

The view subcommand allows you to output the analysis results with a variety of different types (Diagnostic List, Annotated Source, SARIF, Summary), in a variety of mediums (Text, XML, JSON, HTML). Filtering allows the user to finely control what details, from which files make it into the output.

There are several different types of output available and can be chosen using the ‑‑type (‑t). It can have the following values:

• DIAGLST - Outputs a list of diagnostics for each file (containing diagnostics). If no output type is specified, then DIAGLST is the default. See Diagnostic List (DIAGLST) for more information.
• ANNSRC - Embeds the diagnostics output into a copy of the source file. See Annotated Source (ANNSRC) for more information.
• SARIF - Outputs all diagnostics for the project into a single file in SARIF format. See Static Analysis Results Interchange Format (SARIF) for more information.
• SUMMARY - Outputs a severity summary of all diagnostics for the project into a single file. See Severity Summary (SUMMARY) for more information.

The output can be in one of several different formats (or mediums):

• HTML - For each source file, output results to an HTML file.
• JSON - Output results in JSON format (only supported for SARIF output type).
• STDERR - Output results as text, to standard error.
• STDOUT - Output results as text, to standard output.
• XML - For each source file, output results to an XML file.

For those who possess a completely unrestricted license, it is possible to view results on the command line or output them to a file.

Options

Examples

To output the results for a Helix QAC project to standard output, issue the following command:

qacli view -P <directory> --medium STDOUT

To output to standard error, replace STDOUT with STDERR in the above command.

When the argument to the ‑‑medium option is set to HTML, XML or JSON, a directory can be specified. Files will be output to this directory:

qacli view -P <directory> -m HTML --output-path <directory>

The directory must exist. The output will mirror the directory structure of the source files. To flatten the output into a single folder then add ‑‑collate‑output (‑c). Duplicate files will not be overwritten, and their name will have a unique number appended. For example:

foo.txt foo(1).txt foo(2).txt

To show rule information with each primary diagnostic (but not sub-diagnostics):

qacli view -P <directory> -m STDOUT --rules

The ‑‑rules (‑r) option requires either %r or %v to be present in the ‑‑format string parameter. Refer to Default Format Strings for more information.

Multi-homed messages—messages that are not generated for a specific project file but multiple locations—can be displayed in several formats using the ‑‑multi‑homed‑format, ‑D option.

Diagnostic List (DIAGLST)

This is the default output type and produces a list of diagnostics together with any sub-diagnostics. The exact format of the output is controlled by the ‑‑format option. For information on how to alter this, refer to Formatting the Diagnostic String. To produce default output for a project in the current directory, use a command such as:

qacli view -m STDOUT -P .

This will result in output like this example:

// ======= Results for /home/katie_mac/.config/Perforce/Helix-QAC-
2021.2/samples/sample_inspect_c-2021.2/src/inspect.c
/home/katie_mac/.config/Perforce/Helix-QAC-2021.2/samples/sample_inspect_c2021.2/src/inspect.c(0,1): Msg(2:0790) This translation unit makes use of floating types.
/home/katie_mac/.config/Perforce/Helix-QAC-2021.2/samples/sample_inspect_c-
2021.2/src/inspect.c(1,9): Msg(2:4600) The macro 'NULL' is also defined in '<stddef.h>'.
...

Annotated Source (ANNSRC)

To display diagnostics as annotations in the original source code (both source and headers) you should output in annotated source style:

qacli view -P <directory> -m HTML --type ANNSRC

You can add the ‑‑one‑line‑only argument (‑1) to output only those lines from the source code that have diagnostics associated with them:

qacli view -P . -m STDOUT -t ANNSRC -1

Rather than having individual entries for each source file and header separately, it’s possible to embed the headers into the annotated source listing using ‑‑embed‑header‑messages argument (‑e). This form of output is not supported for multi-project CMA solutions.

qacli view -P . -m STDOUT -t ANNSRC -e

The diagnostic output for included files will only show the top-level diagnostic - no sub-diagnostics will be output.

It is also possible to specify how any included diagnostics are formatted using their own formatting string: ‑‑header‑format‑string argument (‑H). The content is identical to the ‑‑format option - refer to Formatting the Diagnostic String.

If no value is provided and a value for ‑‑format is supplied, then this same value will be used as the header format. If both a ‑‑header‑format‑string and ‑‑format are not supplied, then the following default values will be used:

For output to STDOUT and STDERR:

%?u==0%(%?h%(Err%:Msg%)%:-->%F:%l:%c %)(%N) %R(%u, )%t%?v%(\n%v%)

For output to HTML:

%?u==0%(%?h%(Err%:Msg%)%:-->%F:%l:%c %)(<a href=\"%H\">%p-%N</a>) %R(%u, )%t%?v%(<br/>%v%)

For output to XML:

%l%c%n%t

These values are similar to the defaults for ‑‑format, but with leading %?C%(%^%) removed.

Static Analysis Results Interchange Format (SARIF)

The Static Analysis Results Interchange Format (SARIF) is an industry standard format for the output of static analysis tools.

We output to version (2.1.0) of the standard, full details of the standard can be found here (external PDF).

To output in SARIF format use ‑‑type SARIF and ‑‑medium JSON. For example:

qacli view -P <directory> -m JSON --type SARIF

This will output a JSON based SARIF file to the current directory, with the default name project.sarif. If the file already exists, then the command will fail. You can either:

• Remove the file and retry the command.
• Output to a different directory, using the ‑‑output‑path option.
• Output to a different filename, using the ‑‑output‑name option.
• Use the ‑‑collate‑output option so that a unique filename is generated based upon the name, for example project.sarif is first tried, then project(1).sarif etc.

To output to another directory, use the ‑‑output‑path. For example:

qacli view -P <directory> -m JSON --type SARIF --output-path ../frodo

To output to a specific named file, use the ‑‑output‑name. For example:

qacli view -P <directory> -m JSON --type SARIF --output-name My_Sarif_File

The appropriate extension (.sarif) will automatically be added. Both ‑‑output‑path and ‑‑output‑name can be used together to exactly dictate the location and name for the output file.

SARIF files are JSON based and can be very large. They are automatically output in the most efficient representation possible i.e., minimal spacing and newlines, which are not easily readable by a casual observer. For this reason, it may be preferable to pass them through a JSON beautifier. Several are available, including a default one shipped with Python. For example:

python -m json.tool project.sarif > project_formatted.sarif

Severity Summary (SUMMARY)

To output a concise severity summary of a project use ‑‑type SUMMARY. For example:

qacli view -P <directory> -m STDOUT --type SUMMARY

This will output the summary to the console, where it can be redirected to a file if needed.

Naturally, you can also output to a HTML or XML file. By default, the file will be called severity_summary.xml (or .html) and be in the current working directory.

To output to another directory, use ‑‑output‑path. For example:

qacli view -P <directory> -m XML --type SUMMARY --output-path ../frodo

To output to a specific named file, use ‑‑output‑name. For example:

qacli view -P <directory> -m XML --type SUMMARY --output-name My_Sev_Summary

The appropriate extension (.xml or .html) will automatically be added. Both ‑‑output‑path and ‑‑output‑name can be used together to exactly dictate the location and name for the output file.

For XML output an additional schema that describes the file format will be output. It will be called cli_view_severity_summary.xsd

For multi-project CMA solutions one file per underlying project will be created. The name will be severity_summary.xml (or .html), then severity_summary(1).xml and so on.

• Filtering Messages
• Formatting the Diagnostic String
• Formatting the Rule Violation String
• Conditional Formatting
• Message Text Control
• Format Specifier Restrictions
• An Example Message Format
• Default Format Strings
• Formatting in Windows command files (.bat)
• Viewing CMA Projects
• XML Output
• Deprecated Commands

• QA·CLI
• Helix QAC Documentation